Pydantic ai

PydanticAI 에이전트 및 도구 호출을 OpenTelemetry (OTEL). PydanticAI는 Pydantic 팀이 제작한 Python 에이전트 프레임워크로, 생성형 AI를 사용하여 프로덕션 수준의 애플리케이션을 쉽고 타입 안전하게 구축할 수 있게 해줍니다. 모든 에이전트 및 도구 호출을 추적하기 위해 OTEL을 사용합니다.

Weave에서 OTEL 추적에 대한 자세한 정보는 다음을 참조하세요 OTEL 추적을 Weave로 전송하기.

이 가이드는 OTEL을 사용하여 PydanticAI 에이전트 및 도구 호출을 추적하고 Weave에서 해당 추적을 시각화하는 방법을 보여줍니다. 필요한 종속성을 설치하고, Weave로 데이터를 전송하도록 OTEL 추적기를 구성하며, PydanticAI 에이전트와 도구를 계측하는 방법을 배우게 됩니다. 또한 애플리케이션의 모든 에이전트에서 기본적으로 추적을 활성화하는 방법도 확인할 수 있습니다.

사전 요구 사항

시작하기 전에 필요한 OTEL 종속성을 설치하세요:

pip install opentelemetry-sdk OTELemetry-exporter-otlp-proto-http

그런 다음, Weave에서 OTEL 추적 구성.

Weave에서 OTEL 추적 구성

PydanticAI에서 Weave로 추적을 전송하려면 TracerProvider 및 OTLPSpanExporter로 OTEL을 구성하세요. 내보내기를 인증 및 프로젝트 식별을 위한 올바른 엔드포인트 및 HTTP 헤더로 설정하세요.

API 키 및 프로젝트 정보와 같은 민감한 환경 변수를 환경 파일(예: .env)에 저장하고 os.environ를 사용하여 로드하는 것이 좋습니다. 이렇게 하면 자격 증명이 안전하게 보호되고 코드베이스에 포함되지 않습니다.

필수 구성

• Endpoint: https://trace.wandb.ai/otel/v1/traces
• Headers:
  • Authorization: W&B API 키를 사용한 기본 인증
  • project_id: W&B 엔티티/프로젝트 이름(예: myteam/myproject)

설정 예시

다음 코드 스니펫은 PydanticAI 애플리케이션에서 Weave로 OTEL 추적을 전송하기 위해 OTLP 스팬 내보내기 및 추적기 제공자를 구성하는 방법을 보여줍니다.

import base64
import os
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk import trace as trace_sdk
from opentelemetry.sdk.trace.export import SimpleSpanProcessor

# Load sensitive values from environment variables
WANDB_BASE_URL = "https://trace.wandb.ai"
PROJECT_ID = os.environ.get("WANDB_PROJECT_ID")  # Your W&B entity/project name e.g. "myteam/myproject"
WANDB_API_KEY = os.environ.get("WANDB_API_KEY")  # Your W&B API key

OTEL_EXPORTER_OTLP_ENDPOINT = f"{WANDB_BASE_URL}/otel/v1/traces"
AUTH = base64.b64encode(f"api:{WANDB_API_KEY}".encode()).decode()

OTEL_EXPORTER_OTLP_HEADERS = {
    "Authorization": f"Basic {AUTH}",
    "project_id": PROJECT_ID,
}

# Create the OTLP span exporter with endpoint and headers
exporter = OTLPSpanExporter(
    endpoint=OTEL_EXPORTER_OTLP_ENDPOINT,
    headers=OTEL_EXPORTER_OTLP_HEADERS,
)

# Create a tracer provider and add the exporter
tracer_provider = trace_sdk.TracerProvider()
tracer_provider.add_span_processor(SimpleSpanProcessor(exporter))

OTEL로 PydanticAI 에이전트 추적하기

PydanticAI 에이전트를 추적하고 추적 데이터를 Weave로 전송하려면 추적기 제공자로 구성된 InstrumentationSettings 객체를 Agent constructor에 전달하세요. 이렇게 하면 모든 에이전트 및 도구 호출이 OTEL 구성에 따라 추적됩니다.

다음 예제는 추적이 활성화된 간단한 에이전트를 만드는 방법을 보여줍니다. 핵심 단계는 에이전트를 초기화할 때 instrument 인수를 설정하는 것입니다:

from pydantic_ai import Agent
from pydantic_ai.models.instrumented import InstrumentationSettings

# Create a PydanticAI agent with OTEL tracing
agent = Agent(
    "openai:gpt-4o",
    instrument=InstrumentationSettings(tracer_provider=tracer_provider),
)

result = agent.run_sync("What is the capital of France?")
print(result.output)

에이전트에 대한 모든 호출이 추적되어 Weave로 전송됩니다.

OTEL로 PydanticAI 도구 추적하기

Weave는 OTEL로 계측된 모든 PydanticAI 작업을 추적할 수 있으며, 여기에는 에이전트 및 도구 호출이 모두 포함됩니다. 즉, 에이전트가 도구를 호출할 때(예: @agent.tool_plain로 장식된 함수), 도구 입력, 출력 및 모델의 추론을 포함한 전체 상호 작용이 Weave에서 캡처되고 시각화됩니다.

다음 예제는 시스템 프롬프트와 도구가 있는 에이전트를 만드는 방법을 보여줍니다. 에이전트와 도구 모두에 대해 추적이 자동으로 활성화됩니다:

from pydantic_ai import Agent
from pydantic_ai.models.instrumented import InstrumentationSettings

# Create a PydanticAI agent with a system prompt and OTEL tracing
agent = Agent(
    "openai:gpt-4o",
    system_prompt=(
        "You are a helpful assistant that can multiply numbers. "
        "When asked to multiply numbers, use the multiply tool."
    ),
    instrument=InstrumentationSettings(tracer_provider=tracer_provider),
)

# Define a tool
@agent.tool_plain
def multiply(a: int, b: int) -> int:
    """Multiply two numbers."""
    return a * b

# Ask the agent to use the tool
result = agent.run_sync("What is 7 multiplied by 8?")
print(result.output)

에이전트 호출과 도구 호출이 모두 Weave에서 추적되므로 애플리케이션의 전체 추론 및 실행 경로를 검사할 수 있습니다.

기본적으로 모든 에이전트 계측하기

애플리케이션의 모든 PydanticAI 에이전트에 OTEL 추적을 적용하려면 Agent.instrument_all() 메서드를 사용하세요. 이렇게 하면 InstrumentationSettings 매개변수를 명시적으로 지정하지 않은 모든 에이전트에 대해 기본 instrument 인스턴스가 설정됩니다.

from pydantic_ai import Agent
from pydantic_ai.models.instrumented import InstrumentationSettings

# Set up default instrumentation for all agents
Agent.instrument_all(InstrumentationSettings(tracer_provider=tracer_provider))

# Now, any new agent will use this instrumentation by default
agent1 = Agent("openai:gpt-4o")
agent2 = Agent("openai:gpt-4o", system_prompt="Be helpful.")

result = agent1.run_sync("What is the capital of France?")
print(result.output)

이는 구성을 반복하지 않고도 모든 에이전트에서 일관된 추적을 원하는 대규모 애플리케이션에 유용합니다. 자세한 내용은 PydanticAI OTEL 문서를 참조하세요.

더 알아보기

• Weave 문서: OTEL 추적을 Weave로 전송하기
• 공식 OTEL 문서
• 공식 PydanticAI 문서
• PydanticAI GitHub 저장소